home *** CD-ROM | disk | FTP | other *** search
/ Team Palmtops 7 / Palmtops_numero07.iso / WinCE / SDKWindowsCE / HandHeldPCPro30 / sdk.exe / Jupiter SDK / data1.cab / Emulation_Include_Files / dbgapi.h < prev    next >
Encoding:
C/C++ Source or Header  |  1999-02-19  |  6.6 KB  |  185 lines
  1. /*++
  2.  
  3. Copyright (c) 1997-1998 Microsoft Corporation
  4.  
  5. Module Name: dbgapi.h
  6.  
  7. Purpose: Debug Message and Zone APIs.
  8.  
  9. --*/
  10. #ifndef __DBGAPI_H__
  11. #define __DBGAPI_H__
  12.  
  13. #ifdef __cplusplus
  14. extern "C" {
  15. #endif
  16.     
  17. void WINAPIV NKDbgPrintfW(LPWSTR lpszFmt, ...);
  18. void WINAPI WriteDebugLED(WORD wIndex, DWORD dwPattern);
  19.  
  20. /*
  21. @doc    EXTERNAL    KERNEL
  22. @struct DBGPARAM | Debug zone information structure
  23. @comm   The name of the module is used to look for zone initialization
  24.         information in the host PC registry. Zone names are displayed by
  25.         the control app (eg shell) which allows the user to dynamically
  26.         set zones.
  27. @xref   <f DEBUGREGISTER>
  28. */
  29. typedef struct _DBGPARAM {
  30.     WCHAR    lpszName[32];           // @field Name of module
  31.     WCHAR   rglpszZones[16][32];    // @field names of zones for first 16 bits
  32.     ULONG   ulZoneMask;             // @field Current zone Mask
  33. } DBGPARAM, *LPDBGPARAM;
  34.  
  35. /*
  36. @func   BOOL | DEBUGZONE | Associates a mask bit with a zone
  37. @parm   int | bitnum | Bitnumber being defined
  38. @rdesc  A boolean which is TRUE if bitnum in '1' else is FALSE
  39. @ex     Example of use is |
  40.         // associate bit 0 with an info zone
  41.         #define ZONE_INFO   DEBUGZONE(0)
  42.         // we can now use ZONE_INFO as a boolean for anything.
  43.         // We'd typically use it in a DEBUGMSG ...
  44. */
  45. #define DEBUGZONE(n)  (dpCurSettings.ulZoneMask&(0x00000001<<n))
  46.  
  47. #ifdef SHIP_BUILD
  48.  
  49. #define ERRORMSG(cond,printf_exp) ((void)0)
  50. #define RETAILMSG(cond,printf_exp) ((void)0)
  51. #define DEBUGMSG(cond,printf_exp) ((void)0)
  52. #define DEBUGLED(cond,parms) ((void)0)
  53. #define DBGCHK(module,exp) ((void)0)
  54. #define DEBUGCHK(exp) ((void)0)
  55. #define DEBUGREGISTER(hMod) ((void)0)
  56.  
  57. #else 
  58.  
  59. #ifdef DEBUG
  60.  
  61. /*
  62. @func BOOL | DEBUGMSG | Output a debug message conditionally
  63. @parm BOOL | cond | The condition under which the message is printed
  64. @parm <null> | (printf_exp) | A printf style expression to be output. Must be enclosed
  65.       in parentheses. Gets passed on to the <f NKDbgPrintf> function.
  66. @ex   Example of use |
  67.       DEBUGMSG(ZONE_INFO, (L"FOODLL: Entered func1. Param 1 = %d\r\n", par1));
  68. @xref <f RETAILMSG> <tab> <f ERRORMSG> <tab> <f NKDbgPrintf>
  69. */
  70. #define DEBUGMSG(cond,printf_exp)   \
  71.    ((void)((cond)?(NKDbgPrintfW printf_exp),1:0))
  72. #define DBGCHK(module,exp) \
  73.    ((void)((exp)?1:(          \
  74.        NKDbgPrintfW ( TEXT("%s: DEBUGCHK failed in file %s at line %d \r\n"), \
  75.                  (LPWSTR)module, TEXT(__FILE__) ,__LINE__ ),    \
  76.        DebugBreak(), \
  77.        0  \
  78.    )))
  79.  
  80. /*
  81. @func BOOL | DEBUGLED | Output a debug LED pattern conditionally
  82. @parm BOOL | cond | The condition under which the message is printed
  83. @parm <null> | (parms) | The parameters to be passed to the WriteDebugLED
  84.       function.  Must me in parentheses.  First parameter is wIndex and second
  85.       parameter is dwPattern.
  86. @ex   Example of use |
  87.       DEBUGLED(ZONE_INFO, (3, 0x2345);
  88. @xref <f RETAILMSG> <tab> <f ERRORMSG> <tab> <f WriteDebugLED>
  89. */
  90. #define DEBUGLED(cond,parms)   \
  91.    ((void)((cond)?(WriteDebugLED parms),1:0))    
  92.  
  93.  
  94. /*
  95. @func BOOL | DEBUGCHK | Asserts an expression
  96. @parm BOOL | exp | Expression to be asserted
  97. @comm If the expression is false, this will cause a DebugBreak to be hit which
  98.       will cause you to enter the debugger if you are running with one. It will
  99.       also give you the line number and file name where the assert failed.
  100. */
  101. #define DEBUGCHK(exp) DBGCHK(dpCurSettings.lpszName, exp)
  102. extern  DBGPARAM    dpCurSettings;
  103. /*
  104. @func  BOOL | DEBUGREGISTER | Registers debug settings for a process / module
  105. @parm  HINSTANCE | hInstance | If target is a module this is it's hInstance. If
  106.        target is a process this should be NULL.
  107. @comm  This simply calls through to <f RegisterDebugZones>. It assumes that
  108.        there is a variable of name <b dpCurSettings> visible in the code.
  109. */
  110. BOOL WINAPI RegisterDbgZones(HMODULE hMod, LPDBGPARAM lpdbgparam);
  111. #define DEBUGREGISTER(hMod)  RegisterDbgZones(hMod, &dpCurSettings)
  112. #else
  113.  
  114. #define DEBUGMSG(cond,printf_exp) ((void)0)
  115. #define DEBUGLED(cond,parms) ((void)0)
  116. #define DBGCHK(module,exp) ((void)0)
  117. #define DEBUGCHK(exp) ((void)0)
  118. #define DEBUGREGISTER(hMod) ((void)0)
  119.  
  120. #endif
  121.  
  122. /*
  123. @func BOOL | RETAILMSG | Output a message in retail builds
  124. @parm BOOL | cond | The condition under which the message is printed
  125. @parm <null> | (printf_exp) | A printf style expression to be output. Must be enclosed
  126.       in parentheses. This is simply passed in to the <f NKDbgPrintf> function.
  127. @comm This should be used in a very limited fashion since it can increase
  128.       the size of your retail build.
  129. @ex   Example of use |
  130.       RETAILMSG(x==y, (L"FOODLL: Wierdness. x===y = %d\r\n", x));
  131. @xref <f DEBUGMSG> <tab> <f ERRORMSG> <tab> <f NKDbgPrintf>
  132. */
  133. #define RETAILMSG(cond,printf_exp)   \
  134.    ((cond)?(NKDbgPrintfW printf_exp),1:0)
  135.  
  136. /*
  137. @func BOOL | ERRORMSG | Output an error msg
  138. @parm BOOL | cond | The condition under which the message is printed
  139. @parm <null> | (printf_exp) | A printf style expression to be output. Must be enclosed
  140.       in parentheses. This is passed in to the <f NKDbgPrintf> function.
  141. @comm Very similar to <f RETAILMSG> except that this will prefix the message
  142.       with a big bold ERROR and give the file name & line number of the error
  143.       also.
  144. @ex   Example of use |
  145.       ERRORMSG(x==y, (L"FOODLL: Wierdness. x===y = %d\r\n", x));
  146. @xref <f DEBUGMSG> <tab> <f RETAILMSG> <tab> <f NKDbgPrintf>
  147. */
  148. #define ERRORMSG(cond,printf_exp)     \
  149.    ((cond)?(NKDbgPrintfW(TEXT("ERROR: %s line %d: "),TEXT(__FILE__),__LINE__), NKDbgPrintfW printf_exp),1:0)
  150.  
  151. #endif
  152.  
  153. /*
  154. @func BOOL | RETAILLED | Output a LED code in retail builds
  155. @parm BOOL | cond | The condition under which the message is printed
  156. @parm <null> | (parms) | The parameters to be passed to the WriteDebugLED
  157.       function.  Must me in parentheses.  First parameter is wIndex and second
  158.       parameter is dwPattern.
  159. @comm This should be used in a very limited fashion since it can increase
  160.       the size of your retail build.
  161. @ex   Example of use |
  162.       RETAILLED(ZONE_INFO, (3, 0x2345);
  163. @xref <f DEBUGMSG> <tab> <f ERRORMSG> <tab> <f WriteDebugLED>
  164. */
  165. #define RETAILLED(cond,parms) \
  166.    ((void)((cond)?(WriteDebugLED parms),1:0))    
  167.  
  168.  
  169. // some alternate ways to get to these
  170. #define ASSERTMSG(msg, exp) (DEBUGMSG(!exp,(msg)),DBGCHK(TEXT("Unknown"),exp))
  171. #define ASSERT( exp )   DBGCHK(TEXT("Unknown"), exp)
  172. #define ASSERT_IMPLIES( cond, exp ) ASSERT( !(cond) || (exp) )
  173. #ifdef DEBUG
  174. #define VERIFY(exp)  ASSERT(exp)
  175. #else
  176. #define VERIFY(exp)  ((void)(exp))
  177. #endif
  178.  
  179. #ifdef __cplusplus
  180. }
  181. #endif
  182.     
  183. #endif
  184.  
  185.